GetValue<T>(DicomElement,bool,long,T,GetValueDelegate) Method

Summary

Returns the value of a DICOM element.

Syntax

C++/CLI

public T GetValue<T>( 
   DicomElement element, 
   bool tree, 
   long tag, 
   T defaultValue, 
   GetValueDelegate getValueDelegate 
)

public: 
T^ GetValuegeneric<typename T> 
(  
   DicomElement^ element, 
   bool tree, 
   int64 tag, 
   T^ defaultValue, 
   GetValueDelegate^ getValueDelegate 
)

Parameters

element
an item in the data set.

tree
true to evaluate the Data Set as a tree; false to evaluate the Data Set as a list.

tag
tag of the item to find.

defaultValue
a value of type T that is returned if the actual value cannot be retrieved.

getValueDelegate
an optional delegate that converts that extracted data to any type.

Type Parameters

T
specifies the type of the value to return

Return Value

a value of type T that is the value of the DICOM element

Remarks

This method is used to retrieve a value from a DICOM element It is very flexible method that can be used to retrieve the value as any of the types below, regardless of the DicomVRType The caller specificies the type T of the value, and the value is converted to this type if possible. The generic type T Object can be any of the following:

String
Byte
DateTime
DicomDateValue
DicomTimeValue
DicomDateTimeValue
Int32
Int16
Double
Single
an array of any of the above types

The versions of GetValue that take a delegate can be used to retrieve ANY type, even if it is not native to DicomDataSet. The data is extracted from the value as a string passed to the provided method. The delegate is optional. Pass null if you do not want to use a delegate. Look at the example to see how to use the delegate. Below is a list of the overloads that take a delegate:

Some versions of GetValue return a reference to DicomDataSet, and return the value as an out parameter. These overloads are intended to be used by chaining them together, to make a very human readable code. See the part of the example that refers to a fluent interface to see how this is done. Below is a list of the overloads that return the type as an out parameter.

Generic GetValue(DicomElement,T,out T)
Generic GetValue(Int64,T,out T)

Some versions of GetValue have a parameter tag. For these versions, a search is done in the data set for an element that has this tag. Some of these overloads may also have element and tree parameters. If so, the search for tag starts at element. The search on the data set is performed as a list or tree depending on the tree parameter. For details on the element and tree parameters, see FindFirstElement

Generic GetValue(DicomElement,Boolean,Int64,T,GetValueDelegate)
Generic GetValue(Int64,T,GetValueDelegate)
Generic GetValue(Int64,T)
Generic GetValue(DicomElement,Boolean,Int64,T)
Generic GetValue(Int64,T,out T)

Other versions of this method do not have a tag parameter. In this case, a reference to the actual element is passed to the function, and the value of this element is returned.

Generic GetValue(DicomElement,T,GetValueDelegate)
Generic GetValue(DicomElement,T)
Generic GetValue(DicomElement,T,out T)

All versions of this method take a defaultValue parameter. This is the value that is returned (or to which the out parameter is set) if the method cannot retrieve the actual value of the element, or if the element has no value. To see if this is the case, check the value of the property GetValueResult. For information on this method, see GetValue.

Example

This example will insert several elements into a DICOM data set, and then retrieve the values using delegates.

using Leadtools; 
using Leadtools.Dicom; 
 
 
///  
public class PersonName 
{ 
   private string[] _innerArray = new string[5] {string.Empty, string.Empty, string.Empty, string.Empty, 
                                               string.Empty }; 
 
   /// Access this person name instance as array. Index range is 
   /// bounded between 0 (family name) and 4 (name suffix). 
   public string this[int index] 
   { 
      set 
      { 
         if (value == null || value.Length < 64) 
            _innerArray[index] = value; 
         else 
            throw new DicomException("Length of new entry exceeds 64 characters."); 
      } 
 
      get { return _innerArray[index]; } 
   } 
 
   private const int _familyNameIndex = 0; 
   private const int _givenNameIndex = 1; 
   private const int _middleNameIndex = 2; 
   private const int _namePrefixIndex = 3; 
   private const int _nameSuffixIndex = 4; 
 
   /// Access person name part family name. 
   public string FamilyName 
   { 
      set 
      { 
         if (value == null || value.Length < 64) 
         { 
            _fullName = null; 
            _innerArray[_familyNameIndex] = value; 
         } 
         else 
            throw new DicomException("Length of family name exceeds 64 characters."); 
      } 
 
      get { return _innerArray[_familyNameIndex]; } 
   } 
 
   /// Access person name part given name. 
   public string GivenName 
   { 
      set 
      { 
         if (value == null || value.Length < 64) 
         { 
            _fullName = string.Empty; 
            _innerArray[_givenNameIndex] = value; 
         } 
         else 
            throw new DicomException("Length of family name exceeds 64 characters."); 
      } 
 
      get { return _innerArray[_givenNameIndex]; } 
   } 
 
   /// Access person name part middle name. 
   public string MiddleName 
   { 
      set 
      { 
         if (value == null || value.Length < 64) 
         { 
            _fullName = string.Empty; 
            _innerArray[_middleNameIndex] = value; 
         } 
         else 
            throw new DicomException("Length of family name exceeds 64 characters."); 
      } 
 
      get { return _innerArray[_middleNameIndex]; } 
   } 
 
   /// Access person name part name prefix. 
   public string NamePrefix 
   { 
      set 
      { 
         if (value == null || value.Length < 64) 
         { 
            _fullName = string.Empty; 
            _innerArray[_namePrefixIndex] = value; 
         } 
         else 
            throw new DicomException("Length of family name exceeds 64 characters."); 
      } 
 
      get { return _innerArray[_namePrefixIndex]; } 
   } 
 
   /// Access person name part name suffix. 
   public string NameSuffix 
   { 
      set 
      { 
         if (value == null || value.Length < 64) 
         { 
            _fullName = string.Empty; 
            _innerArray[_nameSuffixIndex] = value; 
         } 
         else 
            throw new DicomException("Length of family name exceeds 64 characters."); 
      } 
 
      get { return _innerArray[_nameSuffixIndex]; } 
   } 
 
   private string _fullName = string.Empty; 
   /// Access full person name string representation. According 
   /// to the DICOM standard "^" is used as separator of different 
   /// person name parts. 
   public string FullName 
   { 
      set 
      { 
         _fullName = value; 
         if (_fullName != null) 
         { 
            string[] s; 
            int i; 
 
            if (_fullName.Contains("^")) 
               s = _fullName.Split('^'); 
            else 
               s = _fullName.Split(' '); 
 
            for (i = 0; i < s.Length; i++) 
            { 
               if (s[i].Length < 64) 
               { 
                  if (i < _innerArray.Length) 
                     _innerArray[i] = s[i]; 
               } 
               else 
                  throw new DicomException("Length of family name exceeds 64 characters."); 
            } 
            for (int k = i; k < _innerArray.Length; k++) 
               _innerArray[k] = string.Empty; 
         } 
      } 
 
      get 
      { 
         if (_fullName == string.Empty) 
         { 
            _fullName = _innerArray[0]; 
            bool isNotNull = _fullName != string.Empty; 
            int i = 1; 
            while (isNotNull && i < _innerArray.Length) 
            { 
               isNotNull = _innerArray[i] != string.Empty; 
               if (isNotNull) 
                  _fullName += "^" + _innerArray[i]; 
               i++; 
            } 
         } 
         return _fullName; 
      } 
   } 
 
 
   /// Creates a new empty person name instance. 
   public PersonName() { } 
 
   /// Creates a new person name instance from specified full name. 
   /// All person name parts have to be separated by "^" according to 
   /// the DICOM standard. 
   public PersonName(string fullName) 
   { 
      FullName = fullName; 
   } 
 
   /// Creates a new person name instance from the different person name parts. 
   public PersonName(string familyName, string givenName, 
       string middleName, string namePrefix, string nameSuffix) 
   { 
      FamilyName = familyName; 
      GivenName = givenName; 
      MiddleName = middleName; 
      NamePrefix = namePrefix; 
      NameSuffix = nameSuffix; 
   } 
 
   /// Return this person name instance's. 
   public override string ToString() 
   { 
      return FullName; 
   } 
} 
 
void DumpPersonName(PersonName pn) 
{ 
   String sMsg = 
      string.Format("Family Name: {0}\nGiven Name: {1}\nMiddle Name: {2}\nName Prefix: {3}\nName Suffix: {4}", 
      pn.FamilyName, 
      pn.GivenName, 
      pn.MiddleName, 
      pn.NamePrefix, 
      pn.NameSuffix); 
   Console.WriteLine(sMsg); 
} 
 
private void DicomDataSet_GetValueWithDelegateExample() 
{ 
   // Create a DicomDataSet and add a PatientName 
   // Dicom Spec for Value Representation PN (Person Name) 
   // Elements are in this order: 
   // * family name complex 
   // * given name complex 
   // * middle name 
   // * name prefix 
   // * name suffix. 
   DicomDataSet ds = new DicomDataSet(); 
   ds.InsertElementAndSetValue(DicomTag.PatientName, "Smith^John^MiddleName^Mr.^III"); 
 
   // Get a PersonName value of an element by specifying a tag, and using a delegate 
   // Use this form when the type is not native to the dataset 
   // The data is extracted from the field as a string and passed to the provided method. 
   PersonName pn = null; 
 
   pn = ds.GetValue<PersonName>( 
      DicomTag.PatientName, 
      null, 
      delegate (string data) 
      { 
         PersonName t = new PersonName(data); 
         return t; 
      } 
      ); 
   DumpPersonName(pn); 
 
   // Another overload, specifying parent element 
   pn = ds.GetValue<PersonName>( 
      null, 
      true, 
      DicomTag.PatientName, 
      null, 
      delegate (string data) 
      { 
         PersonName t = new PersonName(data); 
         return t; 
      } 
      ); 
   DumpPersonName(pn); 
 
   // Another overload, this time passing in the DICOM element instead of a tag 
   DicomElement element = ds.FindFirstElement(null, DicomTag.PatientName, true); 
   pn = ds.GetValue<PersonName>( 
      element, 
      null, 
      delegate (string data) 
      { 
         PersonName t = new PersonName(data); 
         return t; 
      } 
      ); 
   DumpPersonName(pn); 
}